\chapter{Preparing coarse-grained runs}
\label{sec:usage:cgrun}

\subsection*{Preliminary note}
The coarse-grained run requires the molecule topology on the one hand and suitable potentials on the other. In this chapter, the generation of coarse-grained runs is decribed next, followed by a post-processing of the potential.

If the potential is of such a form that it allows direct fitting of a functional form, the section on post-processing can be skipped. Instead, a program of choice should be used to fit a functional form to the potential. Nevertheless, special attention should be paid to units (angles, bondlengths). The resulting curve can then be specified in the MD package used for simulation. However, most potentials don't allow an easy processing of this kind and tabulated potentials have to be used.

\section{Generating a topology file for a coarse-grained run}
\subsubsection*{WARNING: This section describes experimental features. The exact names and options of the program might change in the near future.  The section is specific to \gromacs support though a generalization for other MD packages is planned.}

The mapping definition is close to a topology needed for a coarse grained run. To avoid redundant work, \prog{csg_gmxtopol} can be used to automatically generate a gromacs topology based on an atomistic reference system and a mapping file.

At the current state, \prog{csg_gmxtopol} can only generate the topology for the first molecule in the system. If more molecule types are present, a special tpr file has to be prepared. The program can be executed by
\begin{verbatim}
  csg_gmxtopol --top topol.tpr --cg map.xml --out cgtop
\end{verbatim}
which will create a file \texttt{cgtop.top}. This file includes the topology for the first molecule including definitions for atoms, bonds, angles and dihedrals. It can directly be used as a topology in \gromacs, however the force field definitions (atom types, bond types, etc.) still have to be added manually.

\section{Post-processing of the potential}
\label{sec:post_processing}
The \votca package provides a collection of scripts to handle potentials. They can be modified, refined, integrated or inter- and extrapolated. These scripts are the same ones as those used for iterative methods in chapter \ref{sec:iterative_methods}. Scripts are called by \prog{csg_call}. A complete list of available scripts can be found in sec. \ref{sec:csg_table}.

The post-processing roughly consists of the following steps (see further explanations below):
\begin{itemize}
  \item (manually) clipping poorly sampled (border) regions
  \item resampling the potential in order to change the grid to the proper format (\prog{csg_resample})
  \item extrapolation of the potential at the borders (\prog{csg_call} table extrapolate)
  \item exporting the table to xvg (\prog{csg_call} convert\_potential gromacs)
\end{itemize}

\subsection{Clipping of poorly sampled regions}
Regions with an irregular distribution of samples should be deleted first. This is simply done by editing the \progopt{.pot} file and by deleting those values.

Alternatively, manually check the range where the potential still looks good and is not to noisy and set the flags in the potential file of the bad parts by hand to \texttt{o} (for \texttt{out of range}). Those values will later be extrapolated and overwritten.

\subsection{Resampling}
Use the command
\begin{verbatim}
  csg_resample --in table.pot --out table_resample.pot \
               --grid min:step:max
\end{verbatim}
to resample the potential given in file --\progopt{table.pot} from \progopt{min} to \progopt{max} with a grid spacing of \progopt{step} steps. The result is written to the file specified by \progopt{out}. Additionally, \prog{csg_resample} allows the specification of spline interpolation (\progopt{spfit}), the calculation of derivatives (\progopt{derivative}) and comments (\progopt{comment}). Check the help (\progopt{help}) for further information.

It is important to note that the values \progopt{min} and \progopt{max} \textit{don't} correspond to the minimum and maximum value in the input file, but to the range of values the potential is desired to cover after extrapolation. Therefore, values in $[ \min,\max ]$ that are not covered in the file are automatically marked by a flag \texttt{o} (for \texttt{out of range}) for extrapolation in the next step.

The potential \textit{don't} have to start at 0, this is done by the export script (to xvg) automatically.

\subsection{Extrapolation}
The following line
\begin{verbatim}
  csg_call table extrapolate [options] table_resample.pot \
           table_extrapolate.pot
\end{verbatim}
calls the extrapolation procedure, which processes the range of values marked by \prog{csg_resample}. The input file is \progopt{table\_resample.pot} created in the last step.

After resampling, all values in the potential file that should be used as a basis for extrapolation are marked with an \texttt{i}, while all values that need extrapolation are marked by \texttt{o}. The command above now extrapolates all \texttt{o} values from the \texttt{i} values in the file. Available options include averaging over a certain number of points (\progopt{avgpoints}), changing the functional form (\progopt{function}, default is quadratic), extrapolating just the left or right region of the file (\progopt{region}) and setting the curvature (\progopt{curvature}).

The output \progopt{table\_extrapolate.pot} of the extrapolation step can now be used for the coarse-grained run. If \gromacs is used as a molecule dynamics package, the potential has to be converted and exported to a suitable \gromacs format as described in the final step.

\subsection{Exporting the table}
Finally, the table is exported to \progopt{xvg}. The conversion procedure requires a small xml file \progopt{table.xml} as shown below:
\begin{verbatim}
  <cg>
    <inverse>
      <gromacs>
        <pot_max>1e8</pot_max>
        <table_end>8.0</table_end>
        <table_bins>0.002</table_bins>
      </gromacs>
    </inverse>
  </cg>
\end{verbatim}
where \progopt{<table\_end>} is the \gromacs \progopt{rvdw+table\_extension} and \progopt{<pot\_max>} is just a number slightly smaller than the upper value of single/ double precision. The value given in \progopt{<table\_bins>} corresponds to the \progopt{step} value of \progopt{csg\_resample -grid min:step:max}.

Using the \progopt{xml} file above, call
\begin{verbatim}
  csg_call --options table.xml --ia-type non-bonded \
    convert_potential gromacs table_extrapolate.pot table.xvg
\end{verbatim}
to convert the extrapolated values in \progopt{table\_extrapolate.pot} to \progopt{table.xvg} (The file will contain the \gromacs C12 parts only which are stored in the sixth und seventh column, this can be changed by adding the \progopt{--ia-type C6} option (for the fourth and fiveth column) or \progopt{--ia-type CB} option (for the second and third column) after \prog{csg_call}. Ensure compatibility with the \gromacs topology. See the \gromacs manual for further information).

To obtain a bond table, run
\begin{verbatim}
  csg_call --ia-type bond --options table.xml convert_potential gromacs \
           table_extrapolate.pot table.xvg
\end{verbatim}
It is also possible to use \texttt{angle} and \texttt{dihedral} as type as well.

Internally \progopt{convert\_potential gromacs} will do the following steps:
\begin{itemize}
\item Resampling of the potential from 0 (or -180 for dihedrals) to \texttt{table\_end} (or 180 for angles and dihedrals) with step size \texttt{table\_bins}. This is needed for gromacs the table must start with 0 or -180.
\item Extrapolate the left side (to 0 or -180) exponentially
\item Extrapolate the right side (to \texttt{table\_end} or 180) exponentially (or constant for non-bonded interactions)
\item Shift it so that the potential is zero at \texttt{table\_end} for non-bonded interactions or zero at the minimum for bonded interaction
\item Calculate the force (assume periodicity for dihedral potentials)
\item Write to the format needed by gromacs
\end{itemize}

\subsection{An example on non-bonded interactions}
\begin{verbatim}
  csg_call pot shift_nonbonded table.pot table.pot.refined
  csg_resample --grid 0.3:0.05:2 --in table.pot.refined \
           --out table.pot.refined
  csg_call table extrapolate --function quadratic --region left \
           table.pot.refined table.pot.refined
  csg_call table extrapolate --function constant --region right \
           table.pot.refined table.pot.refined
\end{verbatim}

\section{Alternatives}
Additionally to the two methods described above, namely (a) providing the MD package directly with a functional form fitted with a program of choice or (b) using \progopt{csg\_resample}, \progopt{csg\_call table extrapolate} and \progopt{csg\_call convert\_potential}, another method would be suitable. This is integrating the force table as follows
\begin{verbatim}
  -Integrate the table
  $csg_call table integrate force.d minus_pot.d
  -multiply by -1
  $csg_call table linearop minus_pot.d pot.d -1 0
\end{verbatim}
